Skip to main content

Mail Service

Overview​

If users are invited to a group chat, it is possible that they will be informed by e-mail. We describe how to set this up here.

Core Components​

1. Mail Job System

  • Leverages Laravel's queue system for asynchronous email processing
  • All emails are dispatched through the SendEmailJob class
  • Emails are placed on a dedicated 'emails' queue for separate processing

2. Mail Templates

  • Uses Blade templating engine for email content
  • Standard templates include:
    • invitation.blade.php: For room invitations with secure links
    • welcome.blade.php: For new user onboarding
    • user_registered.blade.php: For registration confirmation

3. Queue Workers

  • Dedicated queue workers process email jobs independently
  • Configured in run_dev.sh with separate workers for email processing:
php artisan queue:work --queue=mails

Email Workflow​

Job Creation and Dispatch

1. Initiation

  • Controllers create email data with specific templates and recipients
  • The job is dispatched to the 'emails' queue:
SendEmailJob::dispatch($emailData, $user->email, $subjectLine, $viewTemplate)
          ->onQueue('emails');

2. Job Processing

  • Queue workers pick up the job from the 'emails' queue
  • The SendEmailJob::handle() method generates and sends the email
  • All email sending occurs asynchronously, avoiding user-facing delays

3. Error Handling

  • Robust error logging for failed email attempts
  • Failed jobs are recorded in the failed_jobs table
  • Automatic retry logic based on Laravel's queue configuration

Secure Invitation System​

The mail service plays a critical role in the room invitation process:

1. Invitation Email Creation

  • When inviting external users to rooms, the InvitationController generates a secure link
  • The link contains a signed URL with an expiration time (48 hours)
$url = URL::signedRoute('open.invitation', [
    'tempHash' => $validatedData['hash'],
    'slug' => $validatedData['slug']
], now()->addHours(48));

2. Secure Link Handling

  • The email contains a one-time link with encrypted credentials
  • Link includes the temporary hash used for room key decryption
  • Links are cryptographically signed to prevent tampering

3. Invitation Flow

  • User receives email with invitation link
  • Clicking the link directs them to login/registration if needed
  • After authentication, the system automatically processes the invitation
  • The temporary hash is used to decrypt the room key
  • User is added to the room with appropriate permissions

Configuration​

1. Mail Driver Options

  • Configured in config/mail.php
  • Supports multiple mail drivers:
    • SMTP (default production setup)
    • Log driver (default development setup)
    • SES, Postmark, SendMail, etc.

2. Queue Configuration

  • Database driver (default) for reliable mail queue processing
  • Failed job handling with automatic retries
  • Separate queue channel for mail processing

3. Mail Templates

  • Blade-based templates stored in resources/views/emails/
  • Supports HTML formatting and dynamic content
  • Data passed via the $emailData array

Technology Stack​

1. Laravel Mail

  • Built on Laravel's Illuminate\Mail package
  • Uses the Mailable class system for email generation
  • Supports various mail drivers and flexible configuration

2. Laravel Queue

  • Database queue driver for persistence
  • Separate worker processes for email handling
  • Ensures emails don't block main application threads

3. Blade Templating

  • Dynamic email templates with Blade syntax
  • Support for conditional content and styling
  • HTML-formatted emails with secure links

Security Considerations​

1. Signed URLs

  • All invitation links use Laravel's URL signing
  • Prevents tampering and ensures authenticity
  • Time-limited validity (48 hours by default)

2. Secure Information Handling

  • No sensitive keys are transmitted in emails
  • Only encrypted references (hashes) are included
  • Full encryption key exchange happens after authentication

3. Queue Protection

  • Queue contents are encrypted in the database
  • Worker processes run with limited permissions
  • Failed job handling with secure logging

The mail service is an integral part of HAWKI2's secure communication infrastructure, particularly for the invitation system that enables encrypted room access while maintaining the end-to-end encryption model throughout the application.